/**
 * 
 */
package com.raimcomputing.pickforme.service;

import org.omg.CORBA.UnknownUserException;

import com.raimcomputing.pickforme.common.exception.EmailAddressInUseException;
import com.raimcomputing.pickforme.common.exception.InvalidPasswordException;
import com.raimcomputing.pickforme.common.exception.NoSuchUserException;
import com.raimcomputing.pickforme.common.vo.UserVo;

/**
 * Contains the interface for using and interacting with users.
 */
public interface User {

	/**
	 * Creates a user if the UserVo contains no ID and the email address is not already in use.
	 * 
	 * @param user
	 *            The user to add.
	 * @param password
	 *            The desired password.
	 * @return The added user (including ID).
	 * @throws EmailAddressInUseException
	 *             If the email address has been used already.
	 */
	UserVo createUser( UserVo user, String password )
			throws EmailAddressInUseException;

	/**
	 * Tries to retrieve the user data by email address. If the password correctly validates then a
	 * valid user object is returned. Otherwise, an UnknownUserException is thrown.
	 * 
	 * @param email
	 *            The email to retrieve the user.
	 * @param password
	 *            The password to validate.
	 * @return A valid user object.
	 * @throws UnknownUserException
	 *             If the email address does not return a known user.
	 * @throws InvalidPasswordException
	 *             If the passwords does not validate.
	 */
	UserVo validateUser( String email, String password )
			throws NoSuchUserException, InvalidPasswordException;

}
